Release Numbers from Customer

This request release numbers from the customer tenant. Number Release requests are sent to Operator Connect to validate the request.

In this event, the number is released both from the Live Platform and from Operator Connect.

● When deleting using the REST API, only numbers belonging to the same Tenant Id can be deleted in the same action; numbers cannot be deleted per customer.
● Assigned numbers must be unassigned in the customers' Teams admin center before they can be released.

URI

Copy 
{{baseUrl}}/api/v2/oc/numbers/action/release?msTenantId={{msTenantId}}

HTTP Method

POST

Request Parameters

Parameter

Type

Description

msTenantId

string

The Microsoft Azure subscription Tenant Id of the customer.

Request Body

The Query Body includes the phone number that you wish to release.

Phone number validation rules are in accordance with E.164. The E.164 format requires the following:

■ A + sign.
■ Country calling code (international).
■ Local area code.

Local telephone number or subscriber number.

It has the following structure: [+][country code][area code][subscriber number].

Example of a number with E.164 format in the United States:

Telephone number: 415 123 1234

E.164 format number: +14151231234

■ Country code: +1
■ Area code: 415

Phone number ranges should be configured as follows:

Copy 
"phoneNumberRanges": [
{
"start": "+97239764660",
"end": "+97239764670"
}

Example Request

Copy 
[
"+97239764578","+97239764579","+97239764584", "+97239764585", "+97239764586"
]

Example Response

The initial response displays the Task Id.

Parameter

Type

Description

taskId

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the tsk_ms_job string in the prefix is unique for this endpoint.
Copy 
{
    "tsk_msjob_0a57213a-351a-42cc-92db-c00eb29fb465"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'. See Number Release Task Status for details. The time execution of Release numbers request may take time depending on the connection with Microsoft Operator Connect.

Copy 
{
    "totalNumbersCount": 5,
    "id": "tsk_msjob_0a57213a-351a-42cc-92db-c00eb29fb465",
    "status": "CompletedSuccess",
    "details": [
        "{\"Id\":\"0a57213a-351a-42cc-92db-c00eb29fb465\",\"TenantId\":\"2fa5f129-04db-4dd4-ba63-7bd45ba59538\",\"Status\":\"Complete\",\"CreatedAt\":\"2023-11-07T20:16:05.5065971+00:00\",\"CreatedBy\":\"AppId: \\u00277b771eea-e15a-4898-ad1a-8f6be5f1b0bd\\u0027\",\"TelephoneNumbers\":[{\"TelephoneNumber\":\"\\u002B97239764578\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764579\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764584\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764585\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null},{\"TelephoneNumber\":\"\\u002B97239764586\",\"Status\":\"Success\",\"ErrorCode\":null,\"ErrorMessage\":null}],\"ErrorMessage\":null}"
    ],
    "executionMessages": null,
    "outputData": {
        "MsReleaseJobId": "0a57213a-351a-42cc-92db-c00eb29fb465",
        "MsTenantId": "2fa5f129-04db-4dd4-ba63-7bd45ba59538",
        "MsReleaseJobStatus": "Complete",
        "UmpReleaseJobStatus": "Complete",
        "MsReleaseJobCreatedAt": "11/7/2023 8:16:05 PM +00:00",
        "MsReleaseJobCreatedBy": "AppId: '7b771eea-e15a-4898-ad1a-8f6be5f1b0bd'",
        "PendingIntervention": false
    }
}

You can optionally run the Get Customer Numbers request to check that the number has been removed.

HTTP Responses

■ 200 OK

Parameter

Type

Description

totalNumbersCount

integer

Total number of numbers released.

id

string

The task Id that is generated for this action. See Task Status.

status

string

Aggregated status reflecting update status on both the Live Cloud and Operator Connect platforms. One of the following:

■ In Progress
■ Completed Success
■ Completed Failed

The cache mechanism used to Upload numbers is according to Distributed Cache.

details

string

Details includes the following values:

■ Id (task Id)
■ Tenant Id (customer Tenant Id)
■ Status
■ Created At string($date-time)
■ Created By string ($date-time)
■ App Id (customer Tenant App Id)
■ Telephone Numbers:
✔ Telephone Number
✔ Corresponding status for each number
✔ Corresponding Error Code for each number
✔ Corresponding Error Message for each number

executionMessages

null

 Internal debugging messages.

outputData

list array

List array including the following parameters:

■ MsReleaseJobId
■ MsTenantId
■ MsReleaseJobStatus
■ UmpReleaseJobStatus
■ MsReleaseJobCreatedAt
■ MsReleaseJobCreatedBy
■ PendingIntervention

MsReleaseJobId

string

Task Id

MsTenantId

string

Microsoft Tenant customer subscription Id.

MsReleaseJobStatus

string

Indicates the status of the number release request on the Microsoft platform:

■ Pending
■ InProgress
■ Complete
■ Error
■ Failed

UmpReleaseJobStatus

string

Indicates the status of the number release request on the Live Cloud platform:

■ Pending
■ InProgress
■ Complete
■ Error
■ Failed

MsReleaseJobCreatedAt

($date-time)

Timestamp indicating when the Job was created.

MsReleaseJobCreatedBy

string

App Id of the Rest API tenant (seeAuthenticating Connection Using Postman).

PendingIntervention

string

Indicates whether internal debugging is required.

In case you wish to “move/edit” an Operator Connect acquired number, you have to release the number and then reupload the number, with the new parameters. After initiating the release operation, check the status of release job until the status is “CompletedSuccess”. This process may take several minutes.

■ 400 Bad Request: Failure to Release Telephone Numbers
Copy 
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Bad Request",
    "status": 400,
    "detail": "Fail to release telephone numbers: Numbers: [+97239764535] do not belong to the Tenant: 2fa5f129-04db-4dd4-ba63-7bd45ba59538.",
    "traceId": "00-ba6c5c1dc3f885eb904f307fc02f5207-c085acc3e2c4162c-00"
}